Inside Macintosh: QuickDraw GX Objects /

Chapter 2 - Shape Objects / Shape Objects Reference

Functions / Flattening and Unflattening Shape Objects

GXFlattenShape

You can use the GXFlattenShape function to convert the object form of a shape--including all the objects that it references--into a stream format that is public and suitable for storage and parsing.

void GXFlattenShape(gxShape source, gxFlattenFlag flags, 
                  struct gxSpoolBlock *block);

source

A reference to the shape you wish to flatten.

flags

A set of flags that specify whether or not to save additional information with the flattened file.

block

A pointer to a spool block structure. QuickDraw GX uses information in the spool block to create and store the flattened data.

DESCRIPTION

The GXFlattenShape function creates a flattened version of the shape referenced by the source parameter and places it into a buffer pointed to by the spool block specified in the block parameter.

Before calling GXFlattenShape, you need to allocate a spool block structure and a buffer to hold the flattened data, and place a pointer to the buffer and a specification of its size into the spool block. You also place into the spool block a pointer to an application-defined spool function that writes the flattened data from the buffer to a file. The spool function responds to commands from QuickDraw GX to open, write, and close the file used to hold the flattened data.

If your spool block structure specifies nil for the buffer pointer and 0 for its size, QuickDraw GX allocates a default buffer (512 KB in version 1.0 of QuickDraw GX) for you.

Upon completion of the function, QuickDraw GX writes into the spool block the number of bytes of flattened data it has placed into the buffer. It also writes other information into the spool block; your spool function can use that information if you want it to parse the flattened file as flattening occurs. Normally, however, for simple flattening of shapes, your application need not read any of the information returned in the spool block, and your spool function needs to read only the size of the flattened data in the buffer.

Note that flattening a shape causes flattened versions of all its referenced objects, such as its style, ink, and transform--and all of their referenced objects in turn--to be stored as well. To flatten a group of shapes, place them in a picture and flatten the picture.

If you set the gxFontListFlatten, gxFontGlyphsFlatten, or gxFontVariationsFlatten flag in the flags parameter when calling this function, GXFlattenShape creates a tag object and attaches it to the source shape. The tag object is of type 'flst' and lists the names of the fonts referenced in the shape, the individual glyphs used in the shape, or the descriptions of any font variations used in the shape, respectively.

If you set the gxBitmapAliasFlatten flag in the flags parameter when calling this function, GXFlattenShape includes with the flattened shape all image data from any bitmap shapes that are referenced by the shape. If this flag is not set, image data from bitmap shapes whose image data is disk-based is not included in the flattened shape. That image data is not lost, however, because a tag object specifying the file holding the image data is flattened along with the shape.

The flattened stream created by GXFlattenShape consists of a series of opcodes and associated data, following the QuickDraw GX stream format.

SPECIAL CONSIDERATIONS

If the source shape already has a tag object of type 'flst' attached to it, GXFlattenShape replaces that tag with a new tag of type 'flst'; it also posts a tags_of_type_flst_removed warning.

If the block parameter is nil, this function returns a parameter_is_nil error. If
the spool-function pointer in the spool block passed in the block parameter is
nil, this function returns a spoolProcedure_is_nil error. If the spool function signals an error during either flattening or unflattening, QuickDraw GX posts an unflattening_interrupted_by_client error. If the spool function attempts to
call GXFlattenShape, QuickDraw GX posts a procedure_not_reentrant error.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
shape_is_nil
procedure_not_reentrant
parameter_is_nil	(debugging version)
spoolProcedure_is_nil
unflattening_interrupted_by_client
parameter_out_of_range	(debugging version)
inconsistent_parameters	(debugging version)
Warnings
tags_of_type_flst_removed	(debugging version)

SEE ALSO

The spool block structure is described on page 2-49. The format for the application-defined spool function is described on page 2-91.

The format for the flattened data, including all opcodes, is described in the stream format chapter of Inside Macintosh: QuickDraw GX Environment and Utilities.

To convert a flattened shape back to its object-based format, use the GXUnflattenShape function, described in the next section.